---
title: AI SDK v5
---

import { Callout } from "fumadocs-ui/components/callout";

## Overview

Integration with the Vercel AI SDK v5 using the new `useChatRuntime` hook from `@assistant-ui/react-ai-sdk`.  
This provides a streamlined way to integrate AI SDK v5 features including the new streamText API and improved TypeScript support.

## Getting Started

import { Steps, Step } from "fumadocs-ui/components/steps";

<Steps>
  <Step>
  ### Create a Next.JS project

```sh
npx create-next-app@latest my-app
cd my-app
```

  </Step>
  <Step>

### Install AI SDK v5 and `@assistant-ui/react`

```sh npm2yarn
npm install @assistant-ui/react @assistant-ui/react-ai-sdk ai @ai-sdk/openai
```

  </Step>
  <Step>

### Setup a backend route under `/api/chat`

`@/app/api/chat/route.ts`

```tsx
import { openai } from "@ai-sdk/openai";
import { streamText, UIMessage, convertToModelMessages, tool } from "ai";
import { frontendTools } from "@assistant-ui/assistant-stream/ai-sdk";
import { z } from "zod";

// Allow streaming responses up to 30 seconds
export const maxDuration = 30;

export async function POST(req: Request) {
  const {
    messages,
    system,
    tools,
  }: {
    messages: UIMessage[];
    system?: string; // System message forwarded from AssistantChatTransport
    tools?: any; // Frontend tools forwarded from AssistantChatTransport
  } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system, // Use the system message from the frontend if provided
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with frontendTools helper
      ...frontendTools(tools),
      // Backend tools
      get_current_weather: tool({
        description: "Get the current weather",
        inputSchema: z.object({
          city: z.string(),
        }),
        execute: async ({ city }) => {
          return `The weather in ${city} is sunny`;
        },
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}
```

  </Step>
  <Step>

### Wrap your app with `AssistantRuntimeProvider` using `useChatRuntime`

`@/app/page.tsx`

```tsx
"use client";

import { Thread } from "@/components/assistant-ui/thread";
import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

export default function Home() {
  const runtime = useChatRuntime();

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="h-full">
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}
```

  </Step>
</Steps>

## API Reference

### useChatRuntime

Creates a runtime directly with AI SDK v5's `useChat` hook integration.

```tsx
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

const runtime = useChatRuntime({
  api: "/api/chat",
  // All standard useChat options are supported
});
```

<Callout type="info">
  By default, `useChatRuntime` uses `AssistantChatTransport` which automatically
  forwards system messages and frontend tools to your backend API. This enables
  your backend to receive the full context from the Assistant UI.
</Callout>

### Custom Transport Configuration

If you need to customize the transport configuration:

```tsx
import { DefaultChatTransport } from "ai";
import { AssistantChatTransport } from "@assistant-ui/react-ai-sdk";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

// Example 1: Custom API URL while keeping system/tools forwarding
const runtime = useChatRuntime({
  transport: new AssistantChatTransport({
    api: "/my-custom-api/chat", // Custom API URL with forwarding
  }),
});

// Example 2: Disable system/tools forwarding
const runtime = useChatRuntime({
  api: "/api/chat",
  transport: new DefaultChatTransport(), // Standard AI SDK transport without forwarding
});
```

<Callout type="warning">
  When customizing the API URL, you must explicitly use `AssistantChatTransport`
  if you want to keep frontend system messages and tools forwarding. Simply
  passing `api` to `useChatRuntime` will use the default transport
  configuration.
</Callout>

#### Transport Options

- **`AssistantChatTransport`** (default): Automatically forwards system messages and frontend tools from the Assistant UI context to your backend
- **`DefaultChatTransport`**: Standard AI SDK transport without automatic forwarding

### Using Frontend Tools with `frontendTools`

When using `AssistantChatTransport`, frontend tools are forwarded to your backend. Use the `frontendTools` helper to properly integrate them:

```tsx
import { frontendTools } from "@assistant-ui/assistant-stream/ai-sdk";

export async function POST(req: Request) {
  const { messages, system, tools } = await req.json();

  const result = streamText({
    model: openai("gpt-4o"),
    system,
    messages: convertToModelMessages(messages),
    tools: {
      // Wrap frontend tools with the helper
      ...frontendTools(tools),
      // Your backend tools
      myBackendTool: tool({
        // ...
      }),
    },
  });

  return result.toUIMessageStreamResponse();
}
```

The `frontendTools` helper converts frontend tool definitions to the AI SDK format and ensures they are properly handled by the streaming response.

### useAISDKRuntime (Advanced)

For advanced use cases where you need direct access to the `useChat` hook:

```tsx
import { useChat } from "@ai-sdk/react";
import { useAISDKRuntime } from "@assistant-ui/react-ai-sdk";

const chat = useChat();
const runtime = useAISDKRuntime(chat);
```

## Example

For a complete example, check out the [AI SDK v5 example](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ai-sdk-v5) in our repository.
